/**
 * @swagger
 * tags:
 *   name: 用户管理
 *   description: 用户管理相关接口，包括创建、查询、修改、删除用户等操作
 */

/**
 * @swagger
 * components:
 *   schemas:
 *     UserCreate:
 *       type: object
 *       required:
 *         - username
 *         - password
 *         - name
 *       properties:
 *         username:
 *           type: string
 *           description: |
 *             用户名
 *             * 长度3-20个字符
 *             * 只能包含字母、数字和下划线
 *             * 必须唯一
 *           pattern: ^[a-zA-Z0-9_]+$
 *           example: "zhang_san"
 *         password:
 *           type: string
 *           description: |
 *             用户密码
 *             * 长度至少6个字符
 *             * 最长100个字符
 *           format: password
 *           example: "password123"
 *         name:
 *           type: string
 *           description: |
 *             用户真实姓名
 *             * 不能为空
 *             * 最长50个字符
 *           example: "张三"
 *         email:
 *           type: string
 *           format: email
 *           description: |
 *             邮箱地址（可选）
 *             * 必须是有效的邮箱格式
 *           example: "zhangsan@example.com"
 *         role:
 *           type: string
 *           description: |
 *             用户角色（可选）
 *             * student: 学生
 *             * admin: 管理员
 *             * 默认为student
 *           enum: [student, admin]
 *           example: "student"
 *
 *     UserUpdate:
 *       type: object
 *       properties:
 *         name:
 *           type: string
 *           description: |
 *             用户真实姓名
 *             * 不能为空
 *             * 最长50个字符
 *           example: "张三"
 *         email:
 *           type: string
 *           format: email
 *           description: 邮箱地址（可选）
 *           example: "zhangsan@example.com"
 *         role:
 *           type: string
 *           description: |
 *             用户角色（仅管理员可修改）
 *             * student: 学生
 *             * admin: 管理员
 *           enum: [student, admin]
 *           example: "student"
 *         password:
 *           type: string
 *           description: |
 *             新密码（可选）
 *             * 如果提供，长度至少6个字符
 *           format: password
 *           example: "newpassword123"
 *
 *     UserStats:
 *       type: object
 *       properties:
 *         total_users:
 *           type: integer
 *           description: 用户总数
 *           example: 100
 *         total_students:
 *           type: integer
 *           description: 学生用户数量
 *           example: 95
 *         total_admins:
 *           type: integer
 *           description: 管理员数量
 *           example: 5
 */

const express = require('express')
const { body, param, query } = require('express-validator')
const router = express.Router()
const userController = require('../controllers/userController')
const { auth, requireRole } = require('../middleware/auth')
const { handleValidationErrors } = require('../middleware/validation')

// 用户创建验证规则 (管理员用)
const createUserValidation = [
  body('username')
    .trim()
    .isLength({ min: 3, max: 20 })
    .withMessage('用户名长度必须在3-20个字符之间')
    .matches(/^[a-zA-Z0-9_]+$/)
    .withMessage('用户名只能包含字母、数字和下划线'),
  body('password')
    .isLength({ min: 6, max: 100 })
    .withMessage('密码长度至少6个字符'),
  body('name')
    .trim()
    .isLength({ min: 1, max: 50 })
    .withMessage('姓名不能为空且不超过50个字符'),
  body('email')
    .optional({ checkFalsy: true })
    .trim()
    .isEmail()
    .withMessage('邮箱格式不正确')
    .normalizeEmail(),
  body('role')
    .optional()
    .isIn(['student', 'admin'])
    .withMessage("角色必须是 'student' 或 'admin'"),
]

// 用户更新验证规则
const updateUserValidation = [
  body('name')
    .optional()
    .trim()
    .isLength({ min: 1, max: 50 })
    .withMessage('姓名不能为空且不超过50个字符'),
  body('email')
    .optional({ checkFalsy: true })
    .trim()
    .isEmail()
    .withMessage('邮箱格式不正确')
    .normalizeEmail(),
  body('role') // 角色更新通常由管理员操作，在controller中会做权限检查
    .optional()
    .isIn(['student', 'admin'])
    .withMessage("角色必须是 'student' 或 'admin'"),
  body('password') // 允许在更新用户信息时修改密码
    .optional({ checkFalsy: true }) // Allow empty string to not update password
    .isLength({ min: 6, max: 100 })
    .withMessage('新密码长度至少6个字符'),
]

// 路由定义
// 管理员获取用户列表
router.get(
  '/',
  auth,
  requireRole(['admin']),
  [
    // Validation for query parameters
    query('role')
      .optional()
      .isIn(['student', 'admin'])
      .withMessage('无效的角色值'),
    query('page')
      .optional()
      .isInt({ min: 1 })
      .toInt()
      .withMessage('页码必须是正整数'),
    query('limit')
      .optional()
      .isInt({ min: 1, max: 100 })
      .toInt()
      .withMessage('每页数量必须在1-100之间'),
    query('search').optional().trim().escape(), // Basic sanitization for search term
  ],
  handleValidationErrors,
  userController.getUsers
)

// 管理员创建用户
router.post(
  '/',
  auth,
  requireRole(['admin']),
  createUserValidation,
  handleValidationErrors,
  userController.createUser
)

// 获取用户统计信息 (管理员)
router.get('/stats', auth, requireRole(['admin']), userController.getUserStats)

// 获取特定用户信息 (管理员或用户自己)
router.get(
  '/:id',
  auth,
  param('id').isInt().withMessage('用户ID必须是整数'),
  handleValidationErrors,
  userController.getUserById // Controller will handle authz
)

// 更新用户信息 (管理员或用户自己)
router.put(
  '/:id',
  auth,
  param('id').isInt().withMessage('用户ID必须是整数'),
  updateUserValidation,
  handleValidationErrors,
  userController.updateUser // Controller will handle authorization (admin can edit anyone, user can edit self)
)

// 管理员删除用户
router.delete(
  '/:id',
  auth,
  requireRole(['admin']),
  param('id').isInt().withMessage('用户ID必须是整数'),
  handleValidationErrors,
  userController.deleteUser
)

module.exports = router

/**
 * @swagger
 * /api/users:
 *   get:
 *     summary: 获取用户列表
 *     description: |
 *       获取系统中的用户列表
 *       * 仅管理员可访问
 *       * 支持分页
 *       * 支持按角色筛选
 *       * 支持模糊搜索
 *     tags: [用户管理]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: role
 *         description: |
 *           按角色筛选
 *           * student: 学生
 *           * admin: 管理员
 *         schema:
 *           type: string
 *           enum: [student, admin]
 *       - in: query
 *         name: page
 *         description: 页码（从1开始）
 *         schema:
 *           type: integer
 *           minimum: 1
 *       - in: query
 *         name: limit
 *         description: 每页记录数（1-100）
 *         schema:
 *           type: integer
 *           minimum: 1
 *           maximum: 100
 *       - in: query
 *         name: search
 *         description: 搜索关键词（用户名或姓名）
 *         schema:
 *           type: string
 *     responses:
 *       200:
 *         description: 成功获取用户列表
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 users:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/UserCreate'
 *                 total:
 *                   type: integer
 *                   description: 总记录数
 *                 page:
 *                   type: integer
 *                   description: 当前页码
 *                 limit:
 *                   type: integer
 *                   description: 每页记录数
 *       403:
 *         description: 权限不足，需要管理员权限
 */

/**
 * @swagger
 * /api/users:
 *   post:
 *     summary: 创建用户
 *     description: |
 *       创建新用户
 *       * 仅管理员可操作
 *       * 支持创建学生和管理员用户
 *       * 用户名必须唯一
 *     tags: [用户管理]
 *     security:
 *       - bearerAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/UserCreate'
 *     responses:
 *       201:
 *         description: 用户创建成功
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/UserCreate'
 *       400:
 *         description: |
 *           创建失败
 *           * 必填字段缺失
 *           * 字段格式错误
 *           * 用户名已存在
 *       403:
 *         description: 权限不足，需要管理员权限
 */

/**
 * @swagger
 * /api/users/stats:
 *   get:
 *     summary: 获取用户统计信息
 *     description: |
 *       获取系统用户统计信息
 *       * 仅管理员可访问
 *       * 包含用户总数、角色分布等信息
 *     tags: [用户管理]
 *     security:
 *       - bearerAuth: []
 *     responses:
 *       200:
 *         description: 成功获取统计信息
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/UserStats'
 *       403:
 *         description: 权限不足，需要管理员权限
 */

/**
 * @swagger
 * /api/users/{id}:
 *   get:
 *     summary: 获取用户详情
 *     description: |
 *       获取指定用户的详细信息
 *       * 用户可以查看自己的信息
 *       * 管理员可以查看所有用户的信息
 *     tags: [用户管理]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         description: 用户ID
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: 成功获取用户信息
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/UserCreate'
 *       403:
 *         description: 无权查看此用户信息
 *       404:
 *         description: 用户不存在
 *
 *   put:
 *     summary: 更新用户信息
 *     description: |
 *       更新指定用户的信息
 *       * 用户可以修改自己的基本信息
 *       * 管理员可以修改所有用户的信息
 *       * 角色修改仅限管理员
 *     tags: [用户管理]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         description: 用户ID
 *         schema:
 *           type: integer
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/UserUpdate'
 *     responses:
 *       200:
 *         description: 用户信息更新成功
 *       400:
 *         description: |
 *           更新失败
 *           * 字段格式错误
 *           * 邮箱格式无效
 *       403:
 *         description: |
 *           权限不足
 *           * 不能修改其他用户信息
 *           * 无权修改用户角色
 *       404:
 *         description: 用户不存在
 *
 *   delete:
 *     summary: 删除用户
 *     description: |
 *       删除指定用户
 *       * 仅管理员可操作
 *       * 删除后不可恢复
 *       * 不能删除自己的账号
 *     tags: [用户管理]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         description: 用户ID
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: 用户删除成功
 *       403:
 *         description: |
 *           删除失败
 *           * 权限不足
 *           * 不能删除自己的账号
 *       404:
 *         description: 用户不存在
 */
